home *** CD-ROM | disk | FTP | other *** search
/ Cream of the Crop 25 / Cream of the Crop 25.iso / program / vgatx10s.zip / VGATEXT.DOC < prev    next >
Text File  |  1997-04-12  |  33KB  |  710 lines
  1. zVgaText
  2. ============================================================================
  3.  
  4.     Summary  Text-mode VGA palette effects class.
  5.  
  6.     Derived  None.
  7.  
  8.     Remarks  This is a fairly useful class for managing VGA palettes and
  9.              screen effect in text mode. This class can handle the general
  10.              effect of highlight backgrounds, fade ins and outs, color
  11.              pulsing, strobes, gradation, beacons and software simulated
  12.              blinking. The functions may look messy at the beginning, but
  13.              once you get used to them, you will be amazed at the things
  14.              that are possible in text mode. Never let your application
  15.              look dull... it implies the programmer was bored with it :-)
  16.  
  17.     Thanks   Very big thanks go to Chris Dunford for his ASM code and a
  18.              nice text article explaining most of the effects in this class.
  19.              He can be contacted at CompuServe, his ID is 76703,2002.
  20.  
  21.     Notes    The following are some introductory notes on the text mode
  22.              VGA that you might want to know before you look at the class.
  23.              These notes combined with the heavy commenting in the source
  24.              should enable you to understand the inner workings of the class.
  25.  
  26.     Color mapping
  27.     ------------------------------------------------------------------------
  28.  
  29.         As programmers who deal with text mode, we are accustomed to using
  30.         attributes for specifying the color for the output. It is a nice
  31.         and simple relationship (refer to 'conio.h' colors explanation for
  32.         textattr() and similar functions). However, the relationship between
  33.         this attribute and the actual color displayed on the screen is far
  34.         from straight-forward. Before I continue, I should note that the 8
  35.         bit color attributes are actually treated as two 4-bit colors. That
  36.         is, you have color numbers ranging from 0 to 15 and they can be
  37.         either foreground or background.
  38.  
  39.         The color attribute (0-15, the one we use in the programs and the
  40.         one that gets stored in the video RAM), is mapped by the VGA BIOS
  41.         using an array of 16 registers. It is used as an index into that
  42.         array, which in turn selects one of the VGA DAC (Digital-To-Analog)
  43.         palettes. These palettes contain the RGB values for each color.
  44.         The RGB values are 3 6-bit numbers (18 bits) that can range from
  45.         0 to 63 for maximum color saturation.
  46.  
  47.         Basically, the attribute is used as an index into the palette and
  48.         the number in the palette is ANDed with the 2 bits in the VGA color
  49.         select register to get one of the 256 DAC color definitions. (There
  50.         are actually two more ANDings with registers, but since those
  51.         usually have all 1's in them, we can safely ignore those steps
  52.         completely).
  53.  
  54.         There are a couple of ways to change the color associated with an
  55.         attribute: change the attribute itself, change the contents of the
  56.         VGA mapping registers, change the contents of the VGA color select
  57.         register (2 bits) or change the content of the VGA DAC for the color.
  58.  
  59.     Paging Modes
  60.     ------------------------------------------------------------------------
  61.  
  62.         The VGA DAC has 256 entries for the colors and each entry has 18
  63.         bits (6 per RGB value). Since the maximum number we can use from
  64.         the color select register is 2^2 = 4, we can only divide the DAC
  65.         into 4 pages of 64 colors each (those 2 bits always end up as the
  66.         MSB of the attribute after the mapping in the VGA registers). We
  67.         can then select the color with the 6-bit value from the VGA regs.
  68.         This is the default mode of the VGA and it is called mode 0.
  69.  
  70.         There is another mode, called mode 1, which combines the data a
  71.         bit differently. Instead of only 2 bits from the VGA color select
  72.         register, it uses 4, thus enabling us to use 16 palettes with 16
  73.         colors each. We will be using this mode because it is a lot more
  74.         efficient (we only need to change the VGA color select register
  75.         to get to the page) and then we can use the 0-15 attribute to get
  76.         to the actual color. No further mapping will be necessary.
  77.  
  78.     Set up
  79.     ------------------------------------------------------------------------
  80.  
  81.         We can improve the speed of mapping by using a simple setup trick.
  82.         We will set the 16 VGA registers to their number, in order, which
  83.         will cause them to drop out of the calculations completely. The
  84.         0..15 attribute will be combined with the 0..15 page select to get
  85.         to the actual DAC color definition. Here's a brief example:
  86.  
  87.             attribute = 3        ; we need to find the color for attr 3
  88.             VGA registers[3] = 3 ; because we set them up like that
  89.             page select = 4      ; we want to use the color in palette 4
  90.  
  91.             DAC offset = 4*16*3 + 3*3 = 201
  92.  
  93.         Some explanation is in order. First, we decide to find the color
  94.         definition (the RGB values) associated with attribute 3. We look
  95.         into the VGA palette registers (16 of them) at the position of
  96.         the attribute (3). Since we made sure these registers are setup to
  97.         contain their index number, this yields 3 as well (we might as well
  98.         skip this step altogether). But there are 16 palettes that contain
  99.         this particular attribute. We decide to use palette #5 (4, when
  100.         indexing from 0, which they are). Each palette has 16 color
  101.         definitions, 3 bytes each (for the RGB values). To get to the
  102.         offset of the palette, we multiply its index by the size of the
  103.         palette (16*3 = 48). To get to the color definition in the palette
  104.         itself, we multiply the color by the 3 bytes of RGB definitions and
  105.         then simply add the number to the offset. This is the actual offset
  106.         into the VGA DAC registers that have the RGB values of the colors.
  107.  
  108.     Techniques
  109.     ------------------------------------------------------------------------
  110.  
  111.         This class uses a number of techniques for managing the palette
  112.         changes that might be useful to know. First, the VGA state is
  113.         saved (the palette, the DAC, the paging mode, etc.). Then we
  114.         setup our own palette with values 0..15 in it. Then we create
  115.         the default color definitions that correspond to the usual ones
  116.         set up by the BIOS (and the ones the user will be expecting to
  117.         see) in the first palette. Then we copy this palette into all
  118.         other 15 palettes. The reason for doing so is simple: since the
  119.         BIOS is using mode 0, the VGA registers may contain values that
  120.         are larger than 15 (they can go up to 64 actually). When we
  121.         switch to mode 1, those values will have their 2 MS bits masked
  122.         off and will possibly produce the same new values. We prevent
  123.         this by making sure that all registers have valid numbers. Then
  124.         the new color definitions are loaded into the VGA DAC registers.
  125.         Note that there is a difference between modifying the color
  126.         definitions in the class and actually loading them into the VGA.
  127.         Even though it is possible to modify a single color definition,
  128.         it is often a lot more convenient (and efficient) to load the
  129.         entire 16 palettes in one call and thus bring all kinds of changes
  130.         into effect immediately.
  131.  
  132.         The VGA text mode effects require that the value of the color
  133.         select register be updated continuously. This can be done either
  134.         in a routine or in the background. The latter is the approach
  135.         adopted by the class. When you call enable(), it will install a
  136.         timer tick interrupt handler to manage the content of the register
  137.         and thus change palettes in the background, thus creating pulsing,
  138.         flashing, and many other effects.
  139.  
  140.         Note that with each effect you create, you 'lose' one of the base
  141.         attributes you can use as a normal color. This means that if you
  142.         change attribute 4 (red) to be a 'fading cyan', every time you
  143.         try to use this attribute, you'll get the fading cyan. You can't
  144.         have red in your application unless you redefine another attribute
  145.         to be that.
  146.  
  147.     General usage
  148.     ------------------------------------------------------------------------
  149.  
  150.         Generally, you would use one of the following functions: GradeColor,
  151.         SetColor, PulseColor, or BlinkSim to modify the internal DAC user
  152.         palette. You would then call disable() (if the timer is currently
  153.         running) and then call LoadPalettes() to load the new definitions
  154.         into the VGA DAC registers. You can use ResetPalettes() to reset
  155.         the colors to their BIOS defaults. When you want to use one of the
  156.         effects, you need to call enable() to make sure that the timer
  157.         interrupt is running and will be changing the color select register
  158.         (thus mapping into a new palette from the DAC). This means that
  159.         each tick (or couple of ticks), the routine will change the current
  160.         palette (0..15) and the screen will reflect the values for that
  161.         color in this palette. This means that setting different values
  162.         for the same attribute in different palettes of the DAC and then
  163.         simply varying the palette number, the attribute will change its
  164.         appearance (in the background). See the demo provided for examples.
  165.  
  166.  
  167.     ZVGATEXT::ZVGATEXT
  168.     ------------------------------------------------------------------------
  169.  
  170.         Summary  Constructs and initializes the zVgaText object.
  171.  
  172.         Syntax   zVgaText();
  173.  
  174.         Remarks  The constructor takes care of saving the current VGA DAC
  175.                  and registers, the paging mode and video page. Note that
  176.                  the zVgaText object is intended for global usage (i.e.
  177.                  you cannot have more than one active at any point in your
  178.                  program), the constructor will abort the application with
  179.                  an assertion failure if it detects that another zVgaText
  180.                  object is already created. In essence, this simply calls
  181.                  resume() to initialize the object.
  182.  
  183.         See also zVgaText::resume
  184.  
  185.  
  186.     ZVGATEXT::~ZVGATEXT
  187.     ------------------------------------------------------------------------
  188.  
  189.         Summary  Destroys the zVgaText object and restores the VGA state.
  190.  
  191.         Syntax   ~zVgaText();
  192.  
  193.         Remarks  The destructor simply calls suspend() to restore the state
  194.                  of the VGA adapter which was saved by resume(). It will
  195.                  also set the internal running flag to False to indicate
  196.                  the you can create another zVgaText object if you want to.
  197.                  This will also restore the blinking if the 'restoreBlink'
  198.                  flag is set to True.
  199.  
  200.         See also zVgaText::suspend, zVgaText::restoreBlink
  201.  
  202.  
  203.     ZVGATEXT::DETECT
  204.     ------------------------------------------------------------------------
  205.  
  206.         Summary  Detects the presence of a VGA (or compatible) card.
  207.  
  208.         Syntax   static Boolean Detect();
  209.  
  210.         Remarks  This routine detects the presence of a VGA (or SVGA) card.
  211.                  It is mainly intended for use by applications to determine
  212.                  whether to use the zVgaText object. Since all its member
  213.                  functions assume that VGA is installed, you might want to
  214.                  prevent them from running.
  215.  
  216.         Return   True if VGA+ card or False otherwise.
  217.  
  218.  
  219.     ZVGATEXT::RESTOREBLINK
  220.     ------------------------------------------------------------------------
  221.  
  222.         Summary  Flag that tells the suspend() routine to restore blinking.
  223.  
  224.         Syntax   static Boolean restoreBlink;
  225.  
  226.         Remarks  This publicly accessible flag is modified by EnableBlink()
  227.                  when you turn off the blinking of characters (thus allowing
  228.                  all 4 bits for background colors and enabling highlight
  229.                  backgrounds). You can set it manually to False before
  230.                  destroying the zVgaText object [or calling suspend()] so
  231.                  the effect is persistent after program termination.
  232.  
  233.         See also zVgaText::EnableBlink, zVgaText::suspend
  234.  
  235.  
  236.     ZVGATEXT::RESUME
  237.     ------------------------------------------------------------------------
  238.  
  239.         Summary  Initializes the zVgaText object and saves the VGA state.
  240.  
  241.         Syntax   static void resume();
  242.  
  243.         Remarks  This is the routine which saves the contents of the VGA
  244.                  color registers, the paging mode and the DAC RGB values
  245.                  so that the program can restore them with suspend(). It
  246.                  will also setup the initial startup mode of the object.
  247.                  This includes switching to mode 1, setting the VGA registers
  248.                  to map their indices, creating the default 16 color DAC
  249.                  definitions in palette 0 and then copying this palette
  250.                  into the other 15. The net effect will be that the program
  251.                  will look exactly the same as without the zVgaText object,
  252.                  but now it is ready to use the text mode effects it has.
  253.  
  254.         Return   Nothing.
  255.  
  256.         See also zVgaText::LoadPalettes, zVgaText::suspend
  257.  
  258.  
  259.     ZVGATEXT::SUSPEND
  260.     ------------------------------------------------------------------------
  261.  
  262.         Summary  Restores the VGA state and suspends the zVgaText object.
  263.  
  264.         Syntax   static void suspend();
  265.  
  266.         Remarks  This routine will restore the settings saved by resume()
  267.                  and will activate the original mode and registers. It is
  268.                  automatically called by the destructor, so you won't need
  269.                  to call it explicitly. It is useful to call when your
  270.                  application will be shelling (swapping out of memory) and
  271.                  you will need to suspend the internal interrupt handler.
  272.                  This can be done with disable(), but suspend() restores
  273.                  the VGA to its original state, unlike disable().
  274.  
  275.         Return   Nothing.
  276.  
  277.         See also zVgaText::disable, zVgaText::resume
  278.  
  279.  
  280.     ZVGATEXT::ENABLE
  281.     ------------------------------------------------------------------------
  282.  
  283.         Summary  Enable the interrupt palette switching handler.
  284.  
  285.         Syntax   static void enable();
  286.  
  287.         Remarks  This routine will install the timer intercept handler which
  288.                  is used for switching the DAC palettes (enabling the text
  289.                  mode effects). Note that you need to LoadPalettes() after
  290.                  you modify them to transfer the new RGB definitions into
  291.                  the VGA DAC registers. Nothing will happen until you call
  292.                  enable() to start switching the palettes in the background.
  293.  
  294.         Return   Nothing.
  295.  
  296.         See also zVgaText::disable, zVgaText::timerHandler
  297.  
  298.  
  299.     ZVGATEXT::DISABLE
  300.     ------------------------------------------------------------------------
  301.  
  302.         Summary  Suspends the execution of the timer intercept handler.
  303.  
  304.         Syntax   static void disable(char nPalette = 0);
  305.  
  306.         Remarks  This removes the timer intercept handler (if one is
  307.                  installed and sets the current palette number to 'nPalette'.
  308.                  The effect is that the text mode effect stop working and
  309.                  the colors 'freeze' to the colors defined in the selected
  310.                  palette. The usual use would be to leave the default palette
  311.                  number of 0 to be the palette used. This function will not
  312.                  do anything if the timer handler is not enabled with a
  313.                  call to enable() first.
  314.  
  315.         Return   Nothing.
  316.  
  317.         See also zVgaText::enable, zVgaText::timerHandler
  318.  
  319.  
  320.     ZVGATEXT::PULSECOLOR
  321.     ------------------------------------------------------------------------
  322.  
  323.         Summary  Creates a pulsing color over a range of palettes.
  324.  
  325.         Syntax   static void PulseColor(char attr, char delta);
  326.                  static void PulseColor(char attr, char delta,
  327.                                         char start, char end);
  328.  
  329.         Remarks  These routines create a pulsing color definition over a
  330.                  range of palettes. Since the first one simply calls the
  331.                  second version with 0 and 15 for the 'start' and 'end'
  332.                  parameters respectively, we will discuss the second one.
  333.                  A pulsing color is defined as a color definition which
  334.                  gradually changes its intensity from normal to high and
  335.                  back to normal. You specify the attribute 'attr' you
  336.                  need modified (0 to 15), the step value 'delta' and the
  337.                  'start' (0 to 14) and 'end' (1 to 15) palettes to modify.
  338.                  The routine will change the RGB color definition for each
  339.                  of the palettes specified except 'start' itself by making
  340.                  each palette's color definition values different by 'delta'
  341.                  from the previous palette. Note that 'end' must be greater
  342.                  than 'start'. Note that 0-value primaries will not be
  343.                  modified at all. You will want to call ResetPalettes() to
  344.                  set the DAC palettes to the same color definitions for
  345.                  this routine to work. This does not load the modified
  346.                  palettes into the VGA DAC, use LoadPalettes() to do that.
  347.                  You also need to call enable() to start the cycling. The
  348.                  speed and the delta for the cycling are also controllable
  349.                  with the SetDelay() and SetDelta() member functions. Make
  350.                  sure you call disable() before you load the DAC registers.
  351.  
  352.         Return   Nothing.
  353.  
  354.         See also zVgaText::LoadPalettes, zVgaText::ResetPalettes,
  355.                  zVgaText::enable, zVgaText::disable, zVgaText::SetDelay
  356.  
  357.  
  358.     ZVGATEXT::SETCOLOR
  359.     ------------------------------------------------------------------------
  360.  
  361.         Summary  Sets a RGB color definition over a range of palettes.
  362.  
  363.         Syntax   static void SetColor(char attr, char rgb[3]);
  364.                  static void SetColor(char attr, char rgb[3],
  365.                                       char start, char end);
  366.  
  367.         Remarks  These routines set the color definition associated with
  368.                  the attribute 'attr' to the 'rgb' values over a range of
  369.                  palettes. They don't load the modified palettes into the
  370.                  VGA DAC registers. Since the first version simply calls
  371.                  the second with 0 and 15 for the 'start' and 'end' numbers,
  372.                  we will concentrate on the second function version. You
  373.                  select the attribute to modify (0 to 15) with the 'attr'
  374.                  argument and the 3-byte RGB color definition in 'rgb'. Note
  375.                  that each of the three bytes can contain color intensity
  376.                  ranging from 0 to 63. The three bytes are the red, green
  377.                  and blue elements of the definition in that order. The
  378.                  'start' palette number can be from 0 to 14 and the 'end'
  379.                  palette - from 1 to 14 (and it must be greater than the
  380.                  'start' number). This modifies all palettes in the range
  381.                  specified. To load the modified palettes into the VGA DAC
  382.                  registers, call LoadPalettes() and then enable() to start
  383.                  the cycling between them.
  384.  
  385.         Return   Nothing.
  386.  
  387.         See also zVgaText::LoadPalettes, zVgaText::enable
  388.  
  389.  
  390.     ZVGATEXT::GRADECOLOR
  391.     ------------------------------------------------------------------------
  392.  
  393.         Summary  Grades a color definition from one RGB to another.
  394.  
  395.         Syntax   static void GradeColor(char attr, char rgb[3]);
  396.                  static void GradeColor(char attr, char rgb[3],
  397.                                         char start, char end);
  398.  
  399.         Remarks  These routines gradually change any RGB color definition
  400.                  to another over a range of palettes. This allows gradual
  401.                  changes between two colors. The first version simply calls
  402.                  the second with 0 and 15 as the 'start' and 'end' values.
  403.                  You select the attribute to modify with the 'attr' argument
  404.                  and the starting and ending palettes with the 'start' and
  405.                  'end' parameters. The function will use the RGB definition
  406.                  for the attribute in the starting palette and calculate
  407.                  the scaling factors to change it into the 'rgb' definition
  408.                  requested over the range of palettes between 'start' and
  409.                  'end'. The RGB definition specifies the red, green and
  410.                  blue color saturations which can range from 0 to 63 each.
  411.                  The attribute should be between 0 and 15, the 'start'
  412.                  palette - from 0 to 14 and the 'end' - from 1 to 15, with
  413.                  'end' larger than 'start'. The RGB definition in the
  414.                  'start' palette is not modified. The new palettes are not
  415.                  loaded into the VGA DAC (use LoadPalettes() for that). You
  416.                  must call enable() to start cycling the palettes.
  417.  
  418.         Return   Nothing.
  419.  
  420.         See also zVgaText::LoadPalettes, zVgaText::CalcScale
  421.  
  422.  
  423.     ZVGATEXT::BLINKSIM
  424.     ------------------------------------------------------------------------
  425.  
  426.         Summary  Simulates blinking in software.
  427.  
  428.         Syntax   static void BlinkSim(char attr);
  429.  
  430.         Remarks  This routine simulates blinking in software. Unlike all
  431.                  other routines which use 4-bit attributes, this one uses
  432.                  the full 8 bits in the normal foreground/background
  433.                  format (LSB - FG and MSB - BG). It simply modifies the
  434.                  palettes 8-15 for the foreground attribute and puts the
  435.                  RGB values from palette 0 for the background attribute.
  436.                  Since the foreground attribute's palettes 0-7 are not
  437.                  modified, you can use all the special effects provided
  438.                  in that range. This will give you a blinking special
  439.                  effect. How about that? This routine does not load the
  440.                  modified palettes into the VGA DAC registers. You can
  441.                  use LoadPalettes() to do that. You must call enable()
  442.                  to start the actual palette cycling.
  443.  
  444.         Return   Nothing.
  445.  
  446.         See also zVgaText::enable, zVgaText::LoadPalettes
  447.  
  448.  
  449.     ZVGATEXT::FADEOUT
  450.     ------------------------------------------------------------------------
  451.  
  452.         Summary  Fades out (to black) all attributes over the 16 palettes.
  453.  
  454.         Syntax   static void FadeOut(char aDelay = 12);
  455.  
  456.         Remarks  This routine fades out all colors to black and returns.
  457.                  Unlike most other routines, this one actually modifies
  458.                  the VGA DAC and performs the operation before returning.
  459.                  The default delay of 12 milliseconds between steps is
  460.                  usually enough, but you can change it to taylor the speed
  461.                  of the effect (higher values result in slower fading). The
  462.                  routine will modify the VGA DAC registers and you may want
  463.                  to call ResetPalettes() when it is done. Also note that
  464.                  you MUST disable() the timer intercept handler before
  465.                  calling this routine. This function is great for program
  466.                  exits when you would fade out the screen before returning
  467.                  to the command prompt.
  468.  
  469.         Return   Nothing.
  470.  
  471.         See also zVgaText::ResetPalettes, zVgaText::disable
  472.  
  473.  
  474.     ZVGATEXT::FADEIN
  475.     ------------------------------------------------------------------------
  476.  
  477.         Summary  Fades in default colors from black.
  478.  
  479.         Syntax   static void FadeIn(char aDelay = 12);
  480.  
  481.         Remarks  This routine is the opposite of FadeOut() in that it
  482.                  gradually fades in the colors from black to the original
  483.                  (default) attributes. Unlike most other routines, this
  484.                  one does all palette handling and does modify the VGA
  485.                  DAC registers. You MUST call disable() before using this
  486.                  routine to suspend the timer intercept handler. You may
  487.                  also want to use ResetPalettes() after using this function
  488.                  to set the 16 palettes to their default values. This
  489.                  effect is great for program startup where you would fade
  490.                  in the screen of your program instead of simply popping
  491.                  the main application window. It looks more professional.
  492.                  The default delay between the fading steps is set to 12
  493.                  milliseconds and in most cases it is sufficient. You can
  494.                  use different values (greater numbers slow down the effect).
  495.  
  496.         Return   Nothing.
  497.  
  498.         See also zVgaText::disable, zVgaText::ResetPalettes
  499.  
  500.  
  501.     ZVGATEXT::RESETPALETTES
  502.     ------------------------------------------------------------------------
  503.  
  504.         Summary  Sets the 16 palettes to the default color RGB values.
  505.  
  506.         Syntax   static void ResetPalettes();
  507.  
  508.         Remarks  Use this routine to re-initialize the 16 palettes to
  509.                  the default colors used by the VGA BIOS. This will create
  510.                  color definitions with RGB entries that look almost like
  511.                  the defaults. The reason I say 'almost', is because the
  512.                  bright colors will appear dimmer. This is done on purpose
  513.                  because it will give you some room to vary the intensity
  514.                  of those attributes too. This routine resets the internal
  515.                  DAC buffer but does not load the new palettes into the
  516.                  VGA itself. you need to call LoadPalettes() to do that.
  517.                  Usually, you will want to reset the palettes in order to
  518.                  put the color definitions in some predictable known state.
  519.                  Resetting the palettes also sets the current palette to 0.
  520.  
  521.         Return   Nothing.
  522.  
  523.         See also zVgaText::LoadPalettes
  524.  
  525.  
  526.     ZVGATEXT::LOADPALETTES
  527.     ------------------------------------------------------------------------
  528.  
  529.         Summary     Loads the internal palettes into the VGA DAC registers.
  530.  
  531.         Syntax   static void LoadPalettes();
  532.  
  533.         Remarks  This is one of the most important functions you will be
  534.                  using. Whenever you use the member functions to modify
  535.                  the internal palettes (GradeColor, SetColor, PulseColor
  536.                  or BlinkSim), nothing will happen without calling this
  537.                  routine first. This function will reload all 256 color
  538.                  definitions into the VGA DAC registers. Of course, it is
  539.                  possible to modify the contents one by one on a per-need
  540.                  basis, except this is more efficient and lets you modify
  541.                  a lot of definitions in one shot. Before you call this
  542.                  routine, you MUST call disable() to suspend the timer
  543.                  intercept handler if you have one installed. This is to
  544.                  prevent the interrupt from occurring while the BIOS is
  545.                  loading the DAC with the definitions. It won't really
  546.                  hurt much except the display will probably be messed up
  547.                  for an instant. It's just good style. Note that even
  548.                  loading the palettes will not cause the effects to work
  549.                  until you call enable() to install the background handler.
  550.  
  551.         Return   Nothing.
  552.  
  553.         See also zVgaText::enable, zVgaText::disable
  554.  
  555.  
  556.     ZVGATEXT::ENABLEBLINK
  557.     ------------------------------------------------------------------------
  558.  
  559.         Summary  Enables or disables the blinking attribute.
  560.  
  561.         Syntax   static void EnableBlink(Boolean enable);
  562.  
  563.         Remarks  This routine changes the interpretation of the blink bit
  564.                  (the MSB of the attribute). The normal VGA operation is
  565.                  to make the characters blink if this bit is on, thus
  566.                  leaving only 3 bits for a maximum of 8 background colors.
  567.                  If you disable the blinking, you get the 4 bits for a
  568.                  maximum of 16 background colors (which enables you to use
  569.                  bright backgrounds). Since you can easily simulate the
  570.                  blinking with the BlinkSim() function, you might want to
  571.                  do that anyway. Note that resume() will not automatically
  572.                  set this for you, it is up to the programmer. However,
  573.                  calling EnableBlink(True) (which enables the blinking)
  574.                  will set the internal 'restoreBlink' flag to False and
  575.                  EnableBlink(False) which enables the bright backgrounds
  576.                  will set the flag to True. This flag is used by suspend()
  577.                  to see if the mode needs restoring. Since this is what
  578.                  you usually want, you can leave it like that. However,
  579.                  the 'restoreBlink' flag is publicly accessible. This is
  580.                  done so you can set it manually to False after enabling
  581.                  bright backgrounds in the rare case where you might want
  582.                  to preserve the setting after the object has been destroyed
  583.                  (like after program termination, for example).
  584.  
  585.         Return   Nothing.
  586.  
  587.         See also zVgaText::restoreBlink, zVgaText::suspend
  588.  
  589.  
  590.     ZVGATEXT::SETDELAY
  591.     ------------------------------------------------------------------------
  592.  
  593.         Summary  Sets the delay between the palette switching.
  594.  
  595.         Syntax   static void SetDelay(ushort nTicks);
  596.  
  597.         Remarks     This sets the number of ticks that must be skipped before
  598.                  a palette switch occurs in the timer intercept handler (if
  599.                  one is installed and running). The default setting is 1.
  600.                  Higher settings will make the effects slower.
  601.  
  602.         Return   Nothing.
  603.  
  604.         See also zVgaText::setDelta, zVgaText::timerHandler
  605.  
  606.  
  607.     ZVGATEXT::SETDELTA
  608.     ------------------------------------------------------------------------
  609.  
  610.         Summary  Sets the palette delta increment.
  611.  
  612.         Syntax   static void SetDelta(char delta);
  613.  
  614.         Remarks  This sets the palette increment for each step. Whenever
  615.                  a timer palette switch occurs (after the number of ticks
  616.                  defined by SetDelay), the current palette will be changed
  617.                  by that many palettes. The 'delta' value is checked and
  618.                  made a multiple of the current palette number (to ensure
  619.                  proper operation). This can be a negative number, but
  620.                  the timer handler usually controls the direction itself.
  621.                  The default value is 1 which makes palettes increment and
  622.                  decrement in succession. You can set higher values if you
  623.                  want to skip over palettes (and make the changes more
  624.                  abrupt than gradual). This will set the internal value
  625.                  even if the timer handler is not installed.
  626.  
  627.         Return   Nothing.
  628.  
  629.         See also zVgaText::SetDelay, zVgaText::timerHandler
  630.  
  631.  
  632.     ZVGATEXT::GETDACPTR
  633.     ------------------------------------------------------------------------
  634.  
  635.         Summary  Get a pointer to the RGB color definition.
  636.  
  637.         Syntax   static    uchar* GetDacPtr(char attr, char palette);
  638.  
  639.         Remarks     This routine retrieves a pointer to the RGB color definition
  640.                  associated with the attribute 'attr' in the 'palette'
  641.                  palette. This is a protected member and can be only used
  642.                  in derived classes. This takes into consideration the VGA
  643.                  mapping registers and will force correct values for both
  644.                  arguments. The pointer returned can be used to set the
  645.                  RGB values for the attribute in the palette (red, green
  646.                  and blue, in that order). Using the pointer to modify the
  647.                  values will actually affect the internal buffer which will
  648.                  not be loaded into the VGA DAC registers until LoadPalette.
  649.  
  650.         Return   Pointer to the RGB definition in palette for attribute.
  651.  
  652.  
  653.     ZVGATEXT::CALCSCALE
  654.     ------------------------------------------------------------------------
  655.  
  656.         Summary  Calculates the color gradation scale parameters.
  657.  
  658.         Syntax   static void CalcScale(char rgbStart[3], char rgbEnd[3],
  659.                                        char nRange);
  660.  
  661.         Remarks  This protected member function calculates the scaling
  662.                  factor required to change the RGB definition in the
  663.                  'rgbStart' parameter to the one in 'rgbEnd' over a
  664.                  range of 'nRange' palettes. The scale is very simple:
  665.                  it consists of an increment value, a fixup and a fixup
  666.                  range. The increment value (positive or negative) is
  667.                  the number that will be added to the starting definition
  668.                  during each step. The fixup range is the number of steps
  669.                  where the fixup value will be added too. The fixup value
  670.                  will always be either 1 or -1 and is used to compensate
  671.                  for the possible difference after adding all the increments
  672.                  (distributed over the fixup range, which will always be
  673.                  between 0 and 14). This routine works in both directions:
  674.                  it will scale colors either up or down, and will treat
  675.                  all three values (RGB) independently. That is, it creates
  676.                  three different scaling factors (one for each of them).
  677.  
  678.         Return   Nothing.
  679.  
  680.         See also zVgaText::GradeColor
  681.  
  682.  
  683.     ZVGATEXT::TIMERHANDLER
  684.     ------------------------------------------------------------------------
  685.  
  686.         Summary  The actual palette switching timer intercept handler.
  687.  
  688.         Syntax   static void interrupt timerHandler(...);
  689.  
  690.         Remarks     Even though this is a private member, it is documented
  691.                  here to show the mechanism which accomplishes the effect
  692.                  of switching the palettes. On each timer tick, the
  693.                  'countdown' value is decremented. When it reaches 0, it
  694.                  is reset to the value given by SetDelay(). Then the
  695.                  current palette number (always between 0 and 15) is
  696.                  incremented by 'delta' (see the SetDelta() routine). The
  697.                  new value is then checked for validity (i.e. we make sure
  698.                  it's between 0 and 15 again). If we are out of range, we
  699.                  adjust the value and reverse the direction of the increment
  700.                  by negating 'delta'. Then the VGA is instructed to use
  701.                  the new palette (DAC page with 16 color definitions) to
  702.                  display the colors associated with the attributes. It will
  703.                  then chain the old timer handler to give other routines
  704.                  a chance to execute too.
  705.  
  706.         Return   Nothing.
  707.  
  708.         See also zVgaText::SetDelay, zVgaText::SetDelta
  709.  
  710.